PrizmDoc v12.0 - November 15, 2016
PrizmDoc Multi-Server Mode
Working with PrizmDoc > Administering PrizmDoc > Multi-Server Environments > PrizmDoc Multi-Server Mode

The PrizmDoc Backend RESTful Services are designed to run out-of-the-box on a single server. In the single-server mode, the PrizmDoc Backend RESTful Services are listening on port 18681 by default and fulfilling requests entirely on the same server. There is no additional configuration to run in single-server mode. This mode is recommended if you have only one server hosting the PrizmDoc Backend RESTful Services.

If your application requires more bandwidth or processing power than one server can handle, the PrizmDoc Backend RESTful Services provide a mode that enables request load balancing and routing across multiple servers hosting PrizmDoc Server. The following topic discusses the requirements and considerations for running the PrizmDoc Backend RESTful Services in multi-server mode.

Additional topics that support multi-server mode:

Multi-Server Mode

Before getting into the details of multi-server mode, it’s important to understand two things about how the PrizmDoc Server generates and serves content:

The caching behavior mentioned above places some requirements on the PrizmDoc Server running in multi-server mode. Luckily, the PrizmDoc Server itself ensures most of these requirements are met.

How It Works

The multi-server mode of the PrizmDoc Server works by creating a new entry point on each server hosting the PrizmDoc HTTP Service. This new entry point becomes responsible for routing requests to the correct PrizmDoc server, as well as load balancing requests for new RESTful web service resources over all the PrizmDoc servers in the node.

Consider the diagram below which depicts an architecture that employs 3 servers hosting the PrizmDoc HTTP Service within a node. Looking deeper, notice that each server is hosting two entry points:

The Server Entry Point (SEP) will be listening on port 18682 by default. This is the main PrizmDoc HTTP Service entry point for the server. It is responsible for routing requests to the internal services running on the server. It is also the same entry point that handles requests from your application in single-server mode. However, in multi-server mode your application should not send requests directly to the SEP, but instead the requests should be made to the Cloud Entry Point.

The Cloud Entry Point (CEP) will be listening on port 18681 by default. In multi-server mode, the CEP is responsible for routing requests to the correct PrizmDoc server. If you are creating a new RESTful web service resource, the CEP will direct that request to a PrizmDoc server it chooses. If you are working with an existing resource, the CEP will ensure that the request is forwarded on to the server which originally created the resource. Any CEP can route any request to the correct server. This allows you to use a simple load balancer in front of your PrizmDoc servers; simply have the load balancer send incoming requests to any CEP on any server and the CEPs will ensure that the requests are routed to the appropriate machine.

Configuration

After installation, the PrizmDoc HTTP Service will be running in single-server mode. To enable multi-server mode:

  1. Stop the PrizmDoc Server.
  2. Open the central configuration file in a text editor.
  3. Set the network.clustering.enabled value to true, and make sure the network.publicPort and network.clustering.clusterPort values exist and are assigned to valid port numbers:

network.clustering.enabled: true,

network.clutering.clusterPort: 18682

network.publicPort: 18681

  1. Optionally, set the network.clustering.servers value to an array of address values corresponding to each PrizmDoc server on the network node:
    Example
    Copy Code 
    network.clustering.servers: [192.168.0.1, 192.168.0.2, 192.168.0.3]
  2. Save and close the central configuration file.
  3. Start the PrizmDoc Server
If your application makes requests to the PrizmDoc service from another server, ports 18681 and 18682 (or other port values you choose) will need to be opened in the firewall for each server hosting the PrizmDoc service.
The following configuration properties have been deprecated and will be removed in a future release. Alter these properties only if not using the central configuration file.

To enable multi-server mode using legacy configuration:

  1. Stop the PrizmDoc Server.
  2. Open the Watchdog configuration file in a text editor. The default path to this file is:
  1. Set the server_mode value to multi, and make sure the sep_port and cep_port values exist and are assigned to valid port numbers:

    "server_mode": "multi",

    "sep_port": 18681,

    "cep_port": 18682,

  1. Optionally, set the cep_servers value to an array of objects containing address and port values corresponding to each PrizmDoc server on the network node:
Example
Copy Code 
    "cep_servers": [
    {
        "address": "192.168.0.1",
        "port": 18681
    },
    {
        "address": "192.168.0.2",
        "port": 18681
    },
    {
        "address": "192.168.0.3",
        "port": 18681
    }
],
  1. Save and close the Watchdog configuration file.
  2. Start the PrizmDoc Server. 
If your application makes requests to the PrizmDoc Server from another server, ports 18681 and 18682 (or other port values you choose) will need to be opened in the firewall for each server hosting the PrizmDoc Server.

Start-Up

Once the PrizmDoc HTTP Service has been configured and is running on each server, there is one more critical step you must perform before the Cloud Entry Points will able to handle requests successfully. In this step you will inform the Cloud Entry Point on each PrizmDoc server of the other available PrizmDoc servers in the same network node. This list allows any CEP to route requests for existing resources to the correct PrizmDoc server that originally created it, as well as load balance requests for new resources across all servers.

The list of servers is set by a HTTP PUT request to each Cloud Entry Point. Below is an example of the request that would be sent to each Cloud Entry Point (given the sample architecture shown in the diagram above):

Example
Copy Code 
PUT http://192.168.0.1:18682/PCCIS/V1/Service/Properties/Servers
{
    "servers": [
        {
            "address": "192.168.0.1",
            "port": "18681"
        },
        {
            "address": "192.168.0.2",
            "port": "18681"
        },
        {
            "address": "192.168.0.3",
            "port": "18681"
        }
    ]
}

This request would be repeated for the remaining two PrizmDoc servers, the only change being the port specified in the HTTP request.

If the network.clustering.servers value was set in the central configuration file during the configuration step, the list of servers will automatically be initialized to this list on start-up. It may still be overridden by a HTTP PUT request to the Cloud Entry Point, but will initialize to the configured value again on subsequent start-ups unless the network.clustering.servers value is changed in the central configuration file.

Scaling

When PrizmDoc servers are added or removed from the node, it is important that the list of servers held by each Cloud Entry Point is updated to reflect the servers that are actually active. Otherwise, requests will begin failing when routed to a server that does not exist, and new servers will not receive their fair share of new requests because not every PrizmDoc Server in the node is aware of them.

Keeping the server lists updated is a matter of repeating the requests described in the Start-up section above, only with updated JSON data that includes the new list of active servers.

 

 

©2016. Accusoft Corporation. All Rights Reserved.

Send Feedback